/*
 * Copyright 2009 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.google.beepmystuff;

/**
 * The low-level Beep My Stuff HTTP API, documented at
 * http://www.beepmystuff.com/static/apidocs/index.html.
 *
 * @see DefaultBmsLowLevelClient
 * @see BmsClient
 */
public interface BmsLowLevelClient {
  /**
   * Log a user in to to Beep My Stuff to get a valid session token. The session
   * token returned by this call is needed for all authenticated API calls.
   * 
   * @param nickname the nickname of the user who wants to login
   * @param password the API password for the user
   * @return the result of this call
   * 
   * @throws BmsTransportException if the request could not be made, or if the
   *     response was unexpected or unintelligible.
   * @throws BmsApiException if an application-level error occurred.
   */
  BmsClient.LoginResult login(String nickname, String password)
      throws BmsTransportException, BmsApiException;

  /**
   * Add an EAN to the user's library.
   * 
   * @param session the session token returned by the login call
   * @param ean a valid EAN or UPC
   * @param shareWith who the item should be shared with 
   * @return the result of this call
   * 
   * @throws BmsTransportException if the request could not be made, or if the
   *     response was unexpected or unintelligible.
   * @throws BmsApiException if an application-level error occurred.
   */
  BmsClient.AddEanResult addEan(String session, String ean, BmsClient.ShareWith shareWith)
      throws BmsTransportException, BmsApiException;

  /**
   * Returns the path to the user's avatar icon.
   * 
   * @param session the session token returned by the login call
   * @return the path to the icon.
   * 
   * @throws BmsTransportException if the request could not be made, or if the
   *     response was unexpected or unintelligible.
   * @throws BmsApiException if an application-level error occurred.
   */
  String getAvatarPath(String session) throws BmsTransportException,
      BmsApiException;
}
